/* 
 * Recursive inclusion prevention mechanism for routing header file
 * Standard C preprocessor technique to prevent multiple header inclusions
 * Ensures routing-related definitions and declarations are processed once per compilation
 * Maintains clean compilation process and prevents symbol redefinition errors
 */
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __ROUTE_H
#define __ROUTE_H

/* 
 * JSON parsing and generation library inclusion
 * Provides cJSON data structures and functions for JSON format manipulation
 * Essential for routing configuration serialization and deserialization
 * Supports structured data exchange for route management operations
 */
#include "cJSON.h"

/* 
 * Standard integer type definitions inclusion
 * Provides fixed-width integer types like uint8_t, uint32_t for consistent data representation
 * Ensures platform-independent integer sizing and memory layout
 * Critical for network programming and cross-platform compatibility
 */
#include <stdint.h>

/* 
 * Conditional compilation directive for Ethernet interface checking
 * When defined, disables validation checks for eth1 network interface
 * Useful for development environments where eth1 interface may not be present
 * Commented out to enable eth1 checking by default in production builds
 */
//#define NOT_CHECK_ETH1

/* 
 * Conditional logging path configuration based on build type
 * DEBUG mode uses local development log file path for easy access
 * RELEASE mode uses system log directory path for persistent logging
 * Currently commented out but available for logging system implementation
 */
// #ifdef DEBUG
// #define LOG_PATH "wwan_log.txt"
// #else
// #define LOG_PATH "/userdata/log/dial/wwan_log.txt"
// #endif

/* 
 * External function declarations for routing management operations
 * These functions provide comprehensive routing table manipulation capabilities
 * Support route display, configuration, modification, and diagnostic operations
 * Implement both runtime routing changes and persistent configuration management
 */

/* 
 * Display current routing table information for specified network device
 * This function retrieves and presents routing entries associated with the given device
 * Provides comprehensive route information including destinations, gateways, and metrics
 * Supports both IPv4 and IPv6 routing table visualization where applicable
 * 
 * @param dev Network device name to display routes for (e.g., "ppp0", "ppp1", "eth1")
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwan_route_show(char *dev);

/* 
 * Parse JSON formatted string into cJSON object structure
 * This utility function converts string data containing JSON into manipulatable cJSON objects
 * Provides error handling for malformed JSON input and memory allocation failures
 * Essential for configuration file parsing and structured data processing
 * 
 * @param str Input string containing JSON formatted data to parse
 * @return cJSON* Pointer to parsed cJSON object structure, NULL on parsing failure
 */
extern cJSON *string2Json(uint8_t *str);

/* 
 * Configure default route priority for specified network device
 * This function sets the routing metric to prioritize the specified device for default routing
 * Adjusts system routing table to prefer the specified interface for internet traffic
 * Supports dynamic route prioritization based on network conditions and user preferences
 * 
 * @param dev Network device name to set as preferred default route (e.g., "ppp0", "ppp1")
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwan_route_defaultSet(char *dev);

/* 
 * Add static route to specified network device configuration
 * This function creates a persistent static route entry for the specified device
 * Configures both runtime routing table and persistent configuration files
 * Supports complex network topologies with multiple static routes per interface
 * 
 * @param dev Network device name to add route to (e.g., "ppp0", "eth1")
 * @param ip Destination IP address or network for the static route
 * @param mask Network mask defining the scope of the destination network
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwan_route_add(char *dev, char *ip, char *mask);

/* 
 * Remove specific route entry from network device configuration
 * This function deletes a route identified by sequence number from the device configuration
 * Removes both runtime routing table entry and persistent configuration setting
 * Supports selective route removal without affecting other configured routes
 * 
 * @param dev Network device name to remove route from (e.g., "ppp0", "ppp1")
 * @param num Sequence number identifying the specific route to delete
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwan_route_delete(char *dev, char *num);

/* 
 * Initialize and start WWAN connection logging system
 * This function activates comprehensive logging for wireless wide area network operations
 * Captures connection establishment, maintenance, and termination events
 * Provides diagnostic information for network troubleshooting and performance monitoring
 * 
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwwan_log_start(void);

/* 
 * Terminate WWAN connection logging system
 * This function gracefully stops the WWAN logging mechanism and closes log files
 * Ensures all buffered log entries are flushed to persistent storage
 * Releases logging system resources and prepares for application shutdown
 * 
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwwan_log_stop(void);

/* 
 * Send AT command to specified modem device
 * This function transmits Hayes command set (AT commands) to cellular modem devices
 * Supports modem configuration, status querying, and diagnostic operations
 * Implements proper command formatting and response parsing for modem communication
 * 
 * @param command AT command string to send to the modem device
 * @param dev Target modem device identifier for command execution
 * @return uint8_t Command execution status (TRUE for success, FALSE for failure)
 */
extern uint8_t wwan_at_send(char *command, char *dev);

/* 
 * Display current WWAN log contents
 * This function retrieves and presents the contents of WWAN operation logs
 * Supports both real-time log monitoring and historical log review
 * Provides formatted output for easy reading and analysis of network events
 * 
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t wwwan_log_show(void);

/* 
 * Save route configuration to persistent storage
 * This function writes route information to configuration files for persistence across reboots
 * Maintains route settings in structured format for reliable restoration
 * Supports incremental route addition without overwriting existing configurations
 * 
 * @param dev Network device name associated with the route
 * @param ip Destination IP address for the route being saved
 * @param mask Network mask for the route destination specification
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t save_routeMsg(char *dev, char *ip, char *mask);

/* 
 * Remove all route configurations for specified device
 * This function clears all persistent route entries associated with the given network device
 * Provides clean slate for route configuration and device reconfiguration
 * Supports device reset operations and network topology changes
 * 
 * @param dev Network device name to clear all routes for
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
extern uint8_t clear_routeMsg(char *dev);

/* 
 * Validate network device type specification
 * This function verifies that the provided device name represents a supported network interface
 * Checks against known device types (ppp0, ppp1, eth1, etc.) with proper naming conventions
 * Prevents configuration errors by validating device identifiers before operations
 * 
 * @param dev Network device name string to validate
 * @return uint8_t Validation result (TRUE for valid device, FALSE for invalid device)
 */
extern uint8_t is_dev_type_valid(char *dev);

/* 
 * Validate route sequence number specification
 * This function checks if the provided route number falls within acceptable range
 * Ensures route operations target existing routes and prevent out-of-bounds access
 * Provides safety checking for route modification and deletion operations
 * 
 * @param route_num Route sequence number to validate
 * @return uint8_t Validation result (TRUE for valid route number, FALSE for invalid)
 */
extern uint8_t is_route_num_valid(uint8_t route_num);

/* 
 * Extract device-specific key-value pairs from JSON configuration
 * This function retrieves configuration values for specific devices from JSON structures
 * Supports flexible configuration management with device-specific parameter sets
 * Essential for reading and interpreting structured configuration data
 * 
 * @param keyvalue Output buffer for retrieved configuration value
 * @param dev_node JSON node identifier for the target device configuration
 * @return uint8_t Operation status indicator (TRUE for success, FALSE for failure)
 */
uint8_t get_json_dev_keyvalue(char *keyvalue,const char *dev_node);

/* 
 * Locate network configuration node for specified device
 * This function searches JSON configuration structure for device-specific settings
 * Identifies the appropriate configuration section based on device identifier
 * Supports hierarchical configuration organization with device-specific parameters
 * 
 * @param dev Network device name to locate configuration for
 * @return uint8_t Operation status indicator (TRUE if found, FALSE if not found)
 */
uint8_t dev_network_node_fine(const char *dev);

/* 
 * Command execution result structure definition
 * This structure encapsulates the outcome of external command execution
 * Provides comprehensive status reporting including exit codes and error messages
 * Supports robust error handling and detailed failure analysis for system commands
 */
// Define a structure for storing command execution results
struct cmd_result {
    /* 
     * Command exit status code field
     * Stores the return code from command execution (0 typically indicates success)
     * Non-zero values represent various error conditions and failure modes
     * Used for conditional processing based on command execution outcome
     */
    int status;        // Exit status code, 0 indicates success, non-zero indicates failure
    
    /* 
     * Command error output content field
     * Pointer to string containing error messages and diagnostic output from failed commands
     * NULL pointer indicates successful execution with no error output
     * Provides detailed failure information for debugging and user notification
     */
    char *error_output; // Error output content, empty pointer if execution successful
};

/* 
 * End of routing header file inclusion protection
 * Closes the #ifndef __ROUTE_H preprocessor conditional block
 * Completes the recursive inclusion prevention mechanism for routing header
 */
#endif /* __ROUTE_H */